Reference

File List

Before Vahunz can be invoked at all, the file has to be created. Unless otherwise specified (by means of --base-name), it is called vahunz.files.

In this file, every line represents one file to be scanned. The filenames can also contain relative pathnames. That means, sepp.c and hugo/sepp.c are both allowed. But resi:sepp.c will most likely cause problems when the output should be written.

list >vahunz.files lformat=%p%n #?.c

Command Line Options

There are a few command line options available. This is a short description of them. Most are used to influence the output or to change the source for getting the file list etc.

All options have a long and a short form causing the same effect. There exist both flags (like --comment) and options requiring an additional argument (like --output). You can not concatenate several flags, therefore instead of -ci you will have to specify -c -i. Option names are case sensitive.

--help, -h

If this flag is enabled, Vahunz will only display a short message about usage and possible command line options, and exit immediately.

--base-name, -b

Base name for supporting files. The respective extensions .files and .names will be appended automatically to this name.

The default is vahunz, which will expect the file list in vahunz.files and the dictionary in vahunz.names.

Example: --base-name vahunz-sepp would use vahunz-sepp.files and vahunz-sepp.names instead.

--comment, -c

--indent, -i

Preserve indention in output.

Normally redundant white space is reduced to a single blank or linefeed. With this option you can oppress this.

--line, -l

Preserve line numbers in output.

Different to --indent, multiple linefeeds will not be reduced to a single one. Blanks and formfeeds still will.

/* this is a
 * multi-line
 * comment */

This option can be useful for tracing back problems during compilation of the vahunzed sources, as line numbers shown in compiler error messages are the same as in the original sources.

--output, -o

The output directory for the vahunzed files. If it does not already exist, it will be created, and also further recursive sub-directories. Of course, the device itself has to exist.

The default is t:, which will normally cause the output files to vanish after a reset.

If the directory specified does not end with a slash (/) or colon (:), a slash will be appended automatically when creating derived output filenames.

Specifying the current directory as output directory will result in an error message. However, this check is not very smart, and can be undermined in several ways. For example, you can do an

assign current_directory: ""

and use current_directory: as argument for --output. This will result in an attempt to overwrite the original source.

--quiet, -q

Shut up - do not display header message, do not show which file is currently processed and all the other things. Error messages will still show up.

--random-seed, -r

Specify random seed used for generation of vahunzed names. If this is omitted, the current time will be used.

This option can be useful if you want to trace back problems during compilation of vahunzed sources.

Example: --random-seed=17

--store, -s

With this option enabled the vahunzed names will be written to the dictionary. This can be useful for fixing problems in the vahunzed sources.

Example: If a name print_record is vahunzed with u73, the dictionary will contain a line

+print_record=u73

This value, here u73, is only valid until the next vahunzation.

--no-warning, -w

Do not display warnings.

Warnings are usually caused by redefined names in the dictionaries, or an unknown vahunz mode in the first column of a line. These problems will cause the responsible line to be removed from the dictionary when it is updated after the first pass.

This option has no effect on this behavior, the only difference is that with --no-warning these actions are performed in silence.

Dictionaries

There are two dictionaries. By the default, they are named vahunz.names and vahunz.ignore. The later one is also referred to as dignorary. Every line in the dictionary represent exactly one name extracted from the source files.

The first character in every line tells what to do with this name. It represents the vahunz mode. Valid modes are:

Remain/Replace: blank (' ')

Names in this mode will remain in the same in the output. This mode is the default for all names when the dictionary is created, except for the names found in the file list. These will be set to be ignored (see below).

Optionally you can specify an equal sign (=) at the end of the name, followed the name the original should be replaced with. This is usually used to increase the readability and consistency of a program.

Blanks after or before the equal sign are not allowed.

Ignore: hyphen (-)

Tells that the name should be put into the dignorary. It will be treated the same as it would have been marked with a blank. However, it is stored in a separate file, therefore the user will not see it all the time when viewing the dictionary, which contains only the names of interest.

This mode is usually used for names of system libraries.

Vahunz: plus sign (+)

Such names are marked to be vahunzed in the output. Therefore it will be replaced by a random sequence of characters.

If the command line option --store has been specified for the last invocation of Vahunz, every such line will also contain an equal sign, followed by the random name used in the recent vahunzed version of the program. When reading the dictionary the next time, the text after the = will be ignored. To produce the same random names again, use the command line option --random-seed.

New: asterisk (*)

If a name was not already part of the dictionary, it will be added automatically with the first column set to an asterisk. This allows the user to scan the dictionary from time to time for occurrences of this character, and then decide what to do about a new name. Concerning everything else, such names are treated the same as in remain/replace mode.

Unknown modes will cause a warning message, and the line will be ignored.

Although the dictionaries are always written in an alphabetically sorted way, they do not need to be sorted when they are read.

All dictionaries can contains names in every possible mode. For example a name in remain/replace mode can also be stored in the dignorary. However, if the dictionaries are rewritten at the end of the vahunzation, the dignorary will entirely consist of names in ignore mode.